Day 15 初探 Google Calendar API vol.2

15th鐵人賽

guancioul

2023-09-30 23:06:28

1605 瀏覽

分享至

昨天談到了Calendars和Calendarlist這兩個API，本篇會繼續昨天的主題，將這兩個API進行功能的比較。順帶一提，在使用這些API之前，我們必須先取得CalendarID，才能順利存取日曆資料。那麼該如何取得CalendarID呢？

取得CalendarID

CalendarID的取得其實非常簡單，選定Google日曆左下角日曆列表中需要使用的日曆，並點選該日曆最右邊的「選項(options)」，便會出現「設定與共用(setup and share)」的選項。在進入「設定與共用」頁面之後，左側主題列會有「整合日曆（Integrated calendar）」這個選項，點擊後頁面會跳到整合日曆的章節內容，即可查看日曆ID（CalendarID）。

Calendars vs Calendarlist

在取得CalendarsID後，即可使用Calendarlist的get功能查找出以下資訊：

{
	"kind": "calendar#calendarListEntry",
	"etag": "\"XXXXXXXXXXXX\"",
	"id": "XXXXXXXXXXXX",
	"summary": "TEST",
	"timeZone": "Asia/Taipei",
	"colorId": "15",
	"backgroundColor": "#9fc6e7",
	"foregroundColor": "#000000",
	"accessRole": "owner",
	"defaultReminders": [],
	"conferenceProperties": {
		"allowedConferenceSolutionTypes": [
			"hangoutsMeet"
		]
	}
}

另外，如果使用Calendars的get功能進行查找，則會得到以下資訊：

{
	"kind": "calendar#calendar",
	"etag": "\"XXXXXXXXXXXXXX\"",
	"id": "XXXXXXXXXXX",
	"summary": "TEST",
	"timeZone": "Asia/Taipei",
	"conferenceProperties": {
		"allowedConferenceSolutionTypes": [
			"hangoutsMeet"
		]
	}
}

由以上結果可知，在使用Calendars以及Calendarlist進行查找雖然都可以獲取資訊，但可獲得的資料量是不相同的。相較之下Calendarlist的API功能可以獲取更多個人化資料，而Calendars能獲取的資料僅限於時間、摘要等日曆的基本資訊。

在經過一天的研究與試錯之後，才發現Event的API功能可以獲取更細部的日曆資料，且更貼近與Notion整合的需求。因此，接下來要介紹一下event！

Event

Event就是Google Calendar在新增行事曆的內容

一般來說新增Event的畫面會像這樣，下面提供一些Event可能會用到的Parameter

{
  "kind": "calendar#event",
  "etag": etag,
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": datetime,
  "updated": datetime,
  "summary": string,
  "description": string,
  "location": string,
  "colorId": string,
  "creator": {
		...
  },
  "organizer": {
		...
  },
  "start": {
		...
  },
  "end": {
		...
  },
  "endTimeUnspecified": boolean,
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
		...
  },
  "transparency": string,
  "visibility": string,
  "iCalUID": string,
  "sequence": integer,
  "attendees": [
    {
			...
    }
  ],
  "attendeesOmitted": boolean,
  "extendedProperties": {
		...
  },
  "hangoutLink": string,
  "conferenceData": {
		...
  },
  "anyoneCanAddSelf": boolean,
  "guestsCanInviteOthers": boolean,
  "guestsCanModify": boolean,
  "guestsCanSeeOtherGuests": boolean,
  "privateCopy": boolean,
  "locked": boolean,
  "reminders": {
		...
  },
  "source": {
		...
  },
  "workingLocationProperties": {
		...
  },
  "attachments": [
		...
  ],
  "eventType": string
}

這邊大致上show一下event中會有的內容，接下來主要介紹event中會用到的兩隻api，分別為List跟Get

List

主要是根據CalendarId來取得該Calendar中的Event，並且用List的方式列出來

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events

用這串網址加上http request get就可以取得Calendar Event List，這邊一個必要的內容就是要加上calendarId

這邊有一些可以Option的內容先列在下面，之後有使用到的話會再另外介紹。

alwaysIncludeEmail	boolean
eventTypes	string
iCalUID	string
maxAttendees	integer
maxResults	integer
orderBy	string
pageToken	string
privateExtendedProperty	string
q	string
sharedExtendedProperty	string
showDeleted	boolean
showHiddenInvitations	boolean
singleEvents	boolean
syncToken	string
timeMax	datetime
timeMin	datetime
timeZone	string
updatedMin	datetime

打完這隻API後就會取得使用者設定的Event，這個List會列在items裏面，名稱的話會在Summary的欄位，如果是Data only的Event在時間區間會拿到Date，不是的話則會拿到DateTime，response如下

{
 "kind": "calendar#events",
 "etag": "",
 "summary": "",
 "description": "",
 "updated": "2023-09-17T12:04:50.249Z",
 "timeZone": "Asia/Taipei",
 "accessRole": "owner",
 "defaultReminders": [],
 "nextSyncToken": "",
 "items": [
  {
   "kind": "calendar#event",
   "etag": "",
   "id": "",
   "status": "confirmed",
   "htmlLink": "",
   "created": "2023-09-15T06:52:47.000Z",
   "updated": "2023-09-15T06:52:47.033Z",
   "summary": "回宜蘭",
   "creator": {
    "email": "guancioul@gmail.com"
   },
   "organizer": {
    "email": "",
    "displayName": "Grace Calendar",
    "self": true
   },
   "start": {
    "date": "2023-10-07"
   },
   "end": {
    "date": "2023-10-11"
   },
   "transparency": "transparent",
   "iCalUID": "",
   "sequence": 0,
   "reminders": {
    "useDefault": false
   },
   "eventType": "default"
  }.
  {
   "kind": "calendar#event",
   "etag": "",
   "id": "",
   "status": "confirmed",
   "htmlLink": "",
   "created": "2023-09-15T06:53:59.000Z",
   "updated": "2023-09-17T12:04:50.249Z",
   "summary": "Lunch",
   "creator": {
    "email": "guancioul@gmail.com"
   },
   "organizer": {
    "email": "",
    "displayName": "Grace Calendar",
    "self": true
   },
   "start": {
    "dateTime": "2023-10-07T11:30:00+08:00",
    "timeZone": "Asia/Taipei"
   },
   "end": {
    "dateTime": "2023-10-07T14:00:00+08:00",
    "timeZone": "Asia/Taipei"
   },
   "iCalUID": "",
   "sequence": 0,
   "reminders": {
    "useDefault": true
   },
   "eventType": "default"
  }
 ]
}

Get

取得單一一個Event的內容

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

這邊會需要的資料會有CalendarId跟EventId，EventId目前知道取得的方式就是從List中找，如果有其他尋找的方式也歡迎留言討論

Option的選項如下，有使用到的話會另外講解

alwaysIncludeEmail	boolean
maxAttendees	integer
timeZone	string

這邊來看一下Response

{
 "kind": "calendar#event",
 "etag": "",
 "id": "",
 "status": "confirmed",
 "htmlLink": "",
 "created": "2023-09-15T06:54:54.000Z",
 "updated": "2023-09-15T06:54:54.782Z",
 "summary": "運動會",
 "creator": {
  "email": ""
 },
 "organizer": {
  "email": "",
  "displayName": "Grace Calendar",
  "self": true
 },
 "start": {
  "date": "2023-10-21"
 },
 "end": {
  "date": "2023-10-22"
 },
 "transparency": "transparent",
 "iCalUID": "",
 "sequence": 0,
 "reminders": {
  "useDefault": false
 },
 "eventType": "default"
}

基本上取得的資料和List的Item內容很像，就只是這邊是單一個Event呈現而已。

目前知道如何取得Calendar的Event，那明天會開始將Event和Golang進行串接。